Saltar para o conteúdo principal
POST
/
toptimize
/
v1
/
retrieval
[Beta] Retrieve objects
curl --request POST \
  --url https://api.topsort.com/toptimize/v1/retrieval \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "slots": 50,
  "opaqueUserId": "<string>",
  "objectType": "listings",
  "seedProductIds": [
    "<string>"
  ],
  "page": {
    "type": "home",
    "pageId": "<string>",
    "value": "electronics"
  },
  "deviceType": "desktop",
  "mode": "all"
}
'
{
  "objectType": "listings",
  "objects": [
    {
      "id": "<string>",
      "score": 123
    }
  ]
}

Autorizações

​
Authorization
string
header
obrigatório

A valid API key generated in Topsort's UI.

Corpo

application/json

The context information for the predictions, including which metrics to predict.

Request to retrieve objects based on context.

​
slots
integer
obrigatório

How many objects to retrieve.

Intervalo necessário: 1 <= x <= 100
Exemplos:

10

50

​
opaqueUserId
string
obrigatório

The opaque user ID is an anonymized unique identifier that maps to the original user ID without revealing the original value. This identifier allows Topsort to correlate user activity between auctions and user interactions, independent of the user's logged-in status. For apps or sites where users might interact while logged out, we recommend generating a random identifier (UUIDv7) on the first load, storing it on local storage (cookie, local storage, etc), and letting it live for at least a year. Otherwise, if your users are always logged in for interactions, you may use a hash of your customer ID. Correct purchase attribution requires long-lived opaque user IDs consistent between auction and event requests.

Exemplo:

"71303ce0-de89-496d-8270-6434589615e8"

​
objectType
enum<string>
obrigatório

The type of object that needs to be retrieved.

Opções disponíveis:
listings,
banners
​
seedProductIds
string[]
obrigatório
​
page
Page · object

Information about the page where an auction or event occurs.

​
deviceType
enum<string>

The device the user is on.

Opções disponíveis:
desktop,
mobile
Exemplo:

"mobile"

​
mode
enum<string>
padrão:all

Retrieval mode, how to interpret the context to get objects.

Opções disponíveis:
all,
complement,
similar

Resposta

The retrieval results. Each retrieved products is accompanied by their relevancy score.

The result of a retrieval request, containing relevant objects with scores.

​
objectType
enum<string>
obrigatório

The type of object that was predicted.

Opções disponíveis:
listings,
banners
​
objects
object[]
obrigatório

Retrieved objects.